Skip to content

Publish the changelog as Atom and JSON Feed (1.13.89) - #32

Merged
bensynapse merged 4 commits into
mainfrom
docs/changelog-release-feeds
Nov 20, 2026
Merged

bensynapse merged 4 commits into
mainfrom
docs/changelog-release-feeds

Conversation

@bensynapse

@bensynapse bensynapse commented Nov 20, 2026 •

Copy link
Copy Markdown
Member

Adds an Atom feed and a JSON Feed of the changelog, so a developer or a tool can follow new versions of the spec.

Supersedes #16, which is based on an older main and now conflicts.

What changes

  • docs/changelog.atom (Atom 1.0) and docs/changelog.json (JSON Feed 1.1) hold all 115 entries. main() parses CHANGELOG.md once and passes the same entries to changelog.html and to both feeds.
  • Each entry has its version, its date, a title and a summary. It also has its sections with their items and notes, and the client library versions it names. The JSON Feed keeps the parsed fields in a _livetennisapi object on each item, and llms.txt describes that object.
  • An entry's id is its anchor on the page, for example changelog.html#v1.13.88. Its dates come from its heading. A rebuild writes the same bytes, so --check covers both files.
  • The Atom feed follows the corrections log feed on livetennisapi.com. Ids are page anchors and dates are at 00:00Z. The feed carries a self link, an alternate link, the author, the icon and the rights.
  • changelog.html and the docs home link both feeds in their head, Atom first. On the docs home they come before the OpenAPI links, so a reader that picks one feed picks the changelog. The changelog header links them in its text, and its JSON-LD lists them as encodings. llms.txt lists both URLs.
  • truthcheck.sh exempts the feeds as it exempts the page. Both quote old quotas in dated entries.

Fixes on the page

  • Fifteen headings from 1.1.0 to 1.9.3 used an em dash. The page showed them as plain text inside the 1.9.4 entry. They now use a hyphen, and the page has 115 entries, up from 99. The build stops on any heading it cannot read.
  • Six older entries showed raw asterisks and backticks where bold or code text ran onto a second line. Two links in angle brackets showed the brackets. Both now render.

Checks

  • The build fails when the Atom feed breaks an RFC 4287 rule or the JSON Feed breaks a JSON Feed 1.1 rule. The checks are in scripts/changelog_feeds.py and use the standard library only, so CI needs nothing new.
  • The build also reads each entry back from the page's HTML and compares it with both feeds. That covers the version and date, the body, the sections, items and notes, and the client versions. Any difference fails the build.
  • python -m unittest scripts/test_changelog_feeds.py runs 26 tests. They check the committed feeds and break copies to show each rule catches its fault.
  • The Atom feed passes the RELAX NG schema from RFC 4287 Appendix B with lxml. The W3C feed validator, run offline, reports two warnings. One is the self link of a local file. The other is entries that share a date, as in the corrections feed.
  • feedparser reads all 115 Atom entries with their links and dates.
  • build_reference.py --check, truthcheck.sh, both unittest files and Redocly lint pass.

The spec version moves to 1.13.89 with a changelog entry. Nothing on the wire changed.

docs/changelog.atom (Atom 1.0) and docs/changelog.json (JSON Feed 1.1)
hold every entry of the changelog. main() parses CHANGELOG.md once and
hands the same entries to changelog.html and to both feeds. Each feed
entry carries the article HTML of the page, so the feeds cannot drift.

Each entry has its version, its date, its sections with their items, a
summary and the client library versions it names. The JSON Feed keeps
those parsed fields in a _livetennisapi object on each item. An entry's
id is its anchor on the page, and its dates come from its heading. A
rebuild writes the same bytes, so --check covers both files.

The Atom feed follows the corrections log feed on livetennisapi.com.
Ids are page anchors and dates are at 00:00Z. The feed has a self link,
an alternate link, the author, the icon and the rights. Each entry has a
plain text summary.

The build now fails when the Atom feed breaks an RFC 4287 rule or the
JSON Feed breaks a JSON Feed 1.1 rule. It also fails when an entry of
the page is missing from a feed or differs in it.
scripts/changelog_feeds.py holds the writers and the checks, with the
standard library only.
scripts/test_changelog_feeds.py runs them on the committed files and on
broken copies.

changelog.html and the docs home link both feeds in their head. The
changelog header links them in its text, and the page JSON-LD lists
them as encodings. llms.txt lists both URLs. truthcheck.sh exempts the
feeds as it exempts the page, since both quote old quotas in dated
entries.

Fix: fifteen headings from 1.1.0 to 1.9.3 used an em dash. The page
showed them as text inside the 1.9.4 entry. They now use a hyphen, and
the build stops on a heading it cannot read. The page has 115 entries.

The spec version moves to 1.13.89 with a changelog entry. Nothing on
the wire changed.
A review found that the page formatted each line of an item on its own.
Bold or code that wrapped onto a second line was never closed. Six older
entries showed raw asterisks and backticks, and the feeds repeated them.
_md_block now formats an item once all its lines are in. Links written
in angle brackets lose the brackets.

The parity check used to compare the body HTML with itself, in effect.
It now reads each entry's sections back from the page's HTML and
compares them with the JSON Feed. Every field the two feeds share must
also match between them, and the Atom content must be type html.

The feed parse follows _md_block line for line. A repeated section stays
two sections, so a note between them keeps its place. Notes now sit in
their section. A heading with a bracketed version that is not an entry
heading stops the build at any level.

The Atom checker covers more of RFC 4287. Text and html constructs may
not hold child elements, content may name a media type, and a person has
one uri at most. A source counts for the author rule only when it has
an author, and a category scheme must be an IRI. The JSON Feed checker
now accepts author and checks attachments.

A version above the newest published version of a client is a runtime,
not the client, so "Python 3.12.4" no longer counts. llms.txt describes
the _livetennisapi object that the feed's about link points to.
A second review found two client versions the feeds left out.
1.13.88 names JavaScript 1.10.3 and then says what failed in 1.10.2.
1.13.63 names livetennisapi-ai 1.1.0 and then says "until 1.2.1". A bare
version now counts for the client named just before it in the same
item, when it has that version's major number. Those two are the only
versions this adds.

An autolink inside bold, as in "**See <https://example.com>**", broke
the build. The URL match ran on into the closing asterisks. Autolinks
are now linked before md_inline sees the rest of the line.

Entry headings must carry a version of the form x.y.z. The IRI check
refuses a % that does not start a hex escape. Atom content with a src
must be empty and give a media type. JSON Feed content_text must be a
string, and the feeds must not carry it next to content_html. The
parity check also reads the version and date shown in each heading.
The build checks that the docs home links both feeds.

A summary now holds the first two items and says how many more there
are. JSON Feed describes a summary as a sentence or two, and the whole
entry is in the content.
A third review replayed the feed discovery of NetNewsWire 7.3 on the
docs home. It skips JSON Feed links and ranked openapi.json above the
Atom feed, so subscribing to the home page picked the spec. Both feed
links now come straight after the canonical link, Atom first.

A version heading written without ## and underlined on the next line
was dropped from all three outputs. A bracketed version and a dash at
the start of a line now stops the build. So does a version that is not
x.y.z.

An autolink inside a code span stays literal text, in the feeds as on
the page. HTML comments are removed before the page is compared with
the feeds or searched for feed links. Dates with an offset past 23:59
fail the checks, and so does an extension name with a dot.

"The Python client to 1.8.0" now counts as a client version. A bare
version right after spec, API or changelog never does. The feeds came
out the same.
@bensynapse
bensynapse merged commit ce5c3b6 into main Nov 20, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant